Skip to main content

Configuration File

ApertureDB reads server settings from a JSON configuration file. The -cfg flag specifies its path:

./aperturedb -cfg config.json

Without -cfg, ApertureDB reads config.json from the working directory. The server does not start if the file is missing.

Parameters​

All configuration keys are optional. Omitted settings use environment variables or built-in defaults according to the precedence below.

For settings read by the server, the first available value is used:

  1. A nonempty environment variable with prefix ADB_ and the key in upper case, such as ADB_PORT or ADB_SESSION_TOKEN_MAX_AGE_SEC.

  2. The value in the JSON configuration file.

  3. The server’s built-in default.

An empty environment variable falls through to JSON or the default. Use true/false for boolean environment values, decimal numbers for numeric values, and raw text for strings. Do not add JSON quotes around string values in the environment. Shell or deployment-file quoting is separate.

The JSON file is parsed and validated before environment overrides are read. Unknown keys, wrong JSON types, and out-of-range JSON values prevent startup even when an environment variable would override them. Environment values are parsed when the consuming setting is read; the JSON validator does not validate the final merged configuration. Follow the documented ranges for both sources. Restart the consuming process after configuration changes.

These defaults describe the database binary. Deployment packages supply additional values and configure separate processes; see Deployment settings and process boundaries.

The following table describes commonly used parameters:

Parameter

Explanation

Default

master_key

The master key that initializes admin password on the first run.

"" (Range: any string)

port

TCP port for incoming connections

55555 (Range: 1-65535)

enable_health_port

Enable/disable the health check port

false (Range: true/false)

health_port

TCP port for health checks

55563 (Range: 1-65535)

timeout_receive

Enable/disable connection receive timeouts

true (Range: true/false)

network_threads

Threads servicing asynchronous connections; idle clients do not occupy query workers.

Up to 4, based on available CPU cores (Range: 1–1024)

query_threads

Workers executing queries. Separate from the number of accepted connections.

Up to 16, based on available CPU cores (Range: 1–65536)

query_queue_bytes_mb

MiB budget shared by all connections for retained request/response bytes, including streamed blob chunks. Also bounds bytes admitted to the query worker pool and the largest request. Allow headroom above the largest encoded request for metadata and worker bookkeeping; concurrent requests and responses compete for this budget. Exhaustion closes the connection.

256 (Range: > 0)

max_read_transactions

Maximum simultaneous database read transactions, independent of socket count.

Greater of 126 or five times query_threads (Range: 1–1048576)

max_connection_message_size_mb

Maximum native query/response message size in MiB (1,048,576 bytes). A value of 0 uses the libcomm default. Set query_queue_bytes_mb above this limit, with headroom for concurrent retained data and bookkeeping. This does not set HTTP proxy limits.

0 (Range: >= 0)

force_ssl

Flag that indicates whether or not SSL-based communication will be enforced by the server

true (Range: true/false)

db_root_path

Path to the root folder where all files/objects will be stored

db (Range: any valid path)

storage_type

Storage backend: ext4 for local files, s3 for S3, or gs for Google Cloud Storage.

"ext4"

storage_bucket_name

Bucket name for S3 or Google Cloud Storage.

""

storage_credentials

Storage credential JSON encoded as a string. See Deploying ApertureDB for credential examples.

"{}"

log_path

Directory where logs will be placed.

"/tmp" (Range: any valid path)

log_level

Levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively

1 (WARNING) (Range: 0-3)

verbose_log_level

Verbosity level beyond INFO, for debugging. Will set log_level = 0. Check Google glog documentation for details

-1 (no verbosity beyond INFO) (Range: >= -1)

log_cerr_threshold

Specify level of logging which will also be sent to stderr

3 (FATAL) (Range: 0-3)

enable_audit_logs

Enable/disable audit logs

false (Range: true/false)

include_audit_logs

When true, audit logs will be included in ApertureDB logs

false (Range: true/false)

kvgd_db_size

Initial graph database mapping size in MiB. The mapping can grow; this is not a RAM reservation or a physical disk capacity limit.

10 (Range: > 0)

kvgd_db_sync

Enable/disable sync operation to disk on every transaction. When disabled, latency will decrease but data loss may occur in case of crash

true (Range: true/false)

locale_name

Locale used for string comparison

en_US (Range: any valid locale)

zk_servers

Comma-separated list of Zookeeper server:port

"" (Range: any string)

zk_prefix

Same instance of Zookeeper can be used by multiple aperturedb clusters. Each cluster uses a different prefix to provide isolation between clusters. The config parameter zk_prefix specifies the path for the instance.

"testing" (Range: any string)

checkpoints_to_keep

Number of checkpoints that will be kept for recovery

4 (Range: > 0)

seconds_between_checkpoints

Interval in seconds between scheduled checkpoints. At least one new changelog is required; commit count does not trigger an earlier checkpoint.

7200 (2 hours) (Range: > 0)

descriptorset_flusher_interval

Number of seconds between descriptor set cleanup operations

1800 (Range: >= 0)

descriptor_index_cache_size_mb

RAM budget in MiB for immutable descriptor index snapshots, their background copies, and private arrays for eligible HNSW appends. Synchronous and lazy indexing share this cache. Zero disables it. Queries use the transactional LMDB index while a matching snapshot is unavailable.

512 (Range: >= 0, must fit the platform byte count)

The descriptor cache budget includes snapshots still held by queries or construction after cache eviction. HNSW native construction scratch and dirty records remain bounded by the mutation workspace, separately from cache-charged arrays. Eligible owned-array construction accounts for native scratch per worker before admission; it can reduce the worker count or use the serial record path when the available budgets do not fit. Explicit mutation limits remain strict. The cache budget excludes query scratch, graph transaction buffers, and the operating system’s LMDB page cache. The lazily allocated admission observation table is also separate (at most 32 namespaces, about 18 KiB on supported 64-bit platforms). A snapshot whose construction estimate exceeds the budget remains searchable directly from LMDB. Cache construction uses one background worker and never blocks a query waiting for completion.

Automatic admission requires reuse evidence for the same index revision: 32 eligible absent observations, or a later observation at least one second after the current observation window began. A new revision starts a new window; idle time alone does not start a build. When the bounded observation table is full, new namespaces replace its least recently observed entry and qualify immediately. These fixed heuristics are not query-latency or cache-readiness guarantees.

To verify warmup on an otherwise idle server, issue representative queries and observe an increase in descriptor_index_cache_hits_total. These global counters cannot attribute individual requests on a server with other traffic. A nonzero budget, a resident entry, elapsed wall time or a completed build alone does not prove that the current query revision used the cache. reason="deferred" in the rejected-by-reason metric indicates that automatic admission is waiting for reuse evidence. Measure warmup and post-write behavior separately from steady-state resident queries.

Security and connection limits​

These settings apply per server. All values must be positive integers.

Setting

Default

Behavior

session_token_max_age_sec

36000

Session token lifetime in seconds (10 hours).

refresh_token_max_age_sec

360000

Refresh token lifetime in seconds (100 hours).

max_sessions_per_user

1024

Maximum sessions per user. Signing in or refreshing revokes the oldest sessions as needed to stay within the limit.

max_sessions_in_cache

1024

Successful session checks kept for reuse. Lower limits reduce retained authentication data and may require more checks; session lifetime and revocation rules stay the same.

max_remote_connections

32

Connections kept for reuse with external origins. Lower limits may require more connection setup; ongoing requests are unaffected. This does not limit concurrent requests or connections to the database’s own storage.

See Access Control and Remote credentials for session limits and the effects of changing permissions or credentials.

HTTPS origin limits​

These optional integer settings control reads from registered HTTPS origins. They do not configure inbound HTTPS or change the HTTP proxy’s request limit. See HTTPS keys and transport for authentication, URL restrictions, and recovery.

HTTPS fetch controls

JSON key / environment suffix

Default

Range

Scope

https_max_object_size_mb / HTTPS_MAX_OBJECT_SIZE_MB

16 MiB

1–64 MiB

Maximum bytes in one remote object.

https_timeout_ms / HTTPS_TIMEOUT_MS

10000 ms

1–30000 ms

Maximum time for one fetch, also bounded by its remaining active fetch budget.

https_operations_limit / HTTPS_OPERATIONS_LIMIT

4

1–32

Concurrent HTTPS operations/readers per server process.

Prefix the environment suffix with ADB_. Independently, one query has a 64 MiB total download budget, at most 32 HTTPS requests, 60 seconds of cumulative active fetch time, and at most two active fetches. Waiting for the client to consume a lazy blob response does not consume the fetch-time budget. These per-query limits are not increased by the three settings above. A size check can make a HEAD request in addition to a GET. Split large workloads into smaller queries and reduce concurrency when limits are reached; retries also consume resources.

Advanced settings​

These settings control resource limits and background work. Their appropriate values depend on the deployment layout and workload; changes require coordination with the deployment administrator or ApertureData support. The table lists server defaults before package overrides.

Advanced settings

Key

Default

Purpose and JSON range

storage_operations_limit

100

Concurrent object-store operations; integer ≥ 1.

storage_part_size_mb

8

Multipart/cache part size in MiB; integer 5–512.

storage_read_cache_parts

4

Cached parts per reader; integer 1–64. Memory depends on part size.

storage_retry_limit / storage_retry_delay_ms

5 / 200

Retry count (integer ≥ 0) and initial backoff in ms (integer ≥ 1).

objects_partition_count / objects_directory_count

4 / 4096

Object-store layout; integers ≥ 1. Do not change an existing layout casually.

resources_max_storage / resources_check_storage_limit

0 / 99

Storage reference limit in GiB (0 disables this limit) and percentage threshold (number 0–100).

task_executor_threads

100

Executor thread count; integer ≥ 1.

enable_blacklist

0

Connection blacklist switch; JSON integer 0 or 1, not a JSON boolean.

max_failed_connections / blacklist_time_minutes

10 / 5

Blacklist failure threshold and duration in minutes; integers ≥ 1.

kvgd_db_inc_size

0

Graph mapping growth increment in MB; integer ≥ 0.

kvgd_readahead / validate_write_txn

false / false

Graph read-ahead and additional write validation; booleans.

merge_write_request_upto

0

Internal write-merging control; integer ≥ 0.

refresh_dset_on_startup

false

Accepted with no effect. Descriptor indexes are maintained transactionally.

more-info is a string annotation accepted in the JSON file; it changes no server behavior and has no environment override.

ADB_HOST_IP is an environment-only server setting for the advertised host identity; its default is the machine hostname. host_ip is not an accepted JSON key.

Deployment settings and process boundaries​

A client first reaches Lenz for the native protocol, or the web proxy and Lenz for REST. The database is a separate backend. Each process reads its own configuration; changing a database variable does not configure the gateway.

Where to configure a setting

Consumer / purpose

Compose

Helm

OpenTofu

Database bootstrap password

ADB_MASTER_KEY

masterKey.password or masterKey.existingSecret

master_key.password or master_key.existing_secret

Database storage

ADB_STORAGE_TYPE, ADB_STORAGE_BUCKET_NAME, ADB_STORAGE_CREDENTIALS in distributed-cloud

storage.type, storage.bucket, storage.credentials / existingSecret

storage.type, storage.bucket, storage.credentials / existing_secret

Database HTTPS fetch controls

Custom Compose override for each database service’s environment; the published environment template does not forward these keys.

aperturedb.extraEnv.ADB_HTTPS_*

aperturedb.extra_env map with ADB_HTTPS_* keys

Lenz native TLS

LNZ_FORCE_SSL; default false

Enabled by the chart’s Lenz template

Enabled by the module’s Lenz configuration

Web HTTPS certificates

TLS_CERT_DIR and certificate filenames, or TLS_CERT_HOSTNAMES for the generated certificate

tls settings

tls settings

Maximum HTTP request body size

HTTP_BODY_LIMIT; default 268435456 bytes

http.bodyLimit in bytes

http.body_limit in bytes

HTTP upstream inactivity timeout

HTTP_TIMEOUT_SECONDS; default 300 seconds

http.timeoutSeconds

http.timeout_seconds

Web redirect and application URL port

HTTPS_PORT; default 443

http.publicPort; set to the public port, normally 443

http.public_port; set to the public port, normally 443

Workflow HTTP routes

Mount an HTTP route configuration with a Compose override

http.routes

http.routes

Published native port

ADB_TCP_PORT; default 55555

service.port; default 55555; service.nodePort for a fixed node port

service.port; default 55555; service.node_port for a fixed node port

Published Lenz health port

ADB_HEALTH_PORT; default 58085

Not configurable; published on an assigned node port when service.type is NodePort

Not configurable; published on an assigned node port when service.type is NodePort

All three packages set backend ADB_FORCE_SSL=false and use Lenz for native client TLS. In Helm and OpenTofu, native TLS is enabled by default; Compose requires LNZ_FORCE_SSL=true to enforce it. HTTP TLS is configured separately. A certificate alone does not enable Compose’s native TLS requirement.

The web port settings control redirects and application URLs. In Kubernetes, set the public port explicitly when a load balancer forwards to backend NodePorts. Workflow routes and Grafana allow one hour between response reads for interactive sessions.

Compose substitutes only variables named by its template. Exporting an arbitrary ADB_* variable on the host does not inject it into a container. Helm’s aperturedb.extraEnv and OpenTofu’s aperturedb.extra_env add variables to database containers; use the separate Lenz and checkpointer maps for those processes. Prefer named package values when available, and inspect rendered configuration before introducing a duplicate environment key. For examples and lifecycle commands, see Deploying ApertureDB.

Config File Example​

This example sets common parameters to their default values. Omitted parameters use their defaults. For a new database, also set ADB_MASTER_KEY to a strong password before starting the server.

{
"port": 55555,
"network_threads": 4,
"query_threads": 16,
"query_queue_bytes_mb": 256,
"max_read_transactions": 126,
"max_connection_message_size_mb": 0,
"force_ssl": true,
"db_root_path": "db",
"storage_type": "ext4",
"log_path": "/tmp",
"log_level": 1,
"verbose_log_level": -1,
"log_cerr_threshold": 3
}

Default Directories Structure​

ApertureDB creates the following directories under its default data path:

db
├── acl
├── binlogs
├── descriptors
├── graph
├── objects
└── tmp